<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Structure Notation
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot021.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc43">5.1</A>&nbsp;&nbsp;Structure Notation</H2><UL>
<LI><A HREF="umsroot022.html#toc23">Updating Structures</A>
<LI><A HREF="umsroot022.html#toc24">Arity and Functor of Structures</A>
<LI><A HREF="umsroot022.html#toc25">Printing Structures</A>
<LI><A HREF="umsroot022.html#toc26">Inheritance</A>
<LI><A HREF="umsroot022.html#toc27">Visibility</A>
</UL>

<A NAME="chapstruct"></A>
<A NAME="@default143"></A>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> structure notation provides a way to use structures with field names.
It is intended to make programs more readable and easier
to modify, without compromising efficiency
(it is implemented by preprocessing).<BR>
<BR>
A structure is declared by specifying a template like this
<A NAME="@default144"></A>
<A NAME="@default145"></A>
<A NAME="@default146"></A>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local struct( book(author, title, year, publisher) ).
</PRE></BLOCKQUOTE>
Structures with the functor book/4 can then be written as
<A NAME="@default147"></A>
<A NAME="@default148"></A>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
book{}
book{title:'tom sawyer'}
book{title:'tom sawyer', year:1886, author:twain}
</PRE></BLOCKQUOTE>
which translate to the corresponding forms
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
book(_, _, _, _)
book(_, 'tom sawyer', _, _)
book(twain, 'tom sawyer', 1886, _)
</PRE></BLOCKQUOTE>
This transformation is done by the parser, therefore it can
be used in any context and is as efficient as using the structures
directly.<BR>
<BR>
The argument index of a field in a structure can be obtained
using a term of the form
<A NAME="@default149"></A>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
FieldName of StructName
</PRE></BLOCKQUOTE>
E.g. to access (ie. unify) a single argument of a structure,
use arg/3 like this:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
..., arg(year of book, B, Y), ...
</PRE></BLOCKQUOTE>
which is translated into
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
..., arg(3, B, Y), ...
</PRE></BLOCKQUOTE>
If a program is consistently written using <B>curly-brace</B> and <B>of</B>
syntax, then the struct-declaration can be modified (fields added or
rearranged) without having to update the code anywhere else.<BR>
<BR>
<A NAME="toc23"></A>
<H3 CLASS="subsection"><A NAME="htoc44">5.1.1</A>&nbsp;&nbsp;Updating Structures</H3>
To construct an updated structure, i.e. a structure which is similar
to an existing structure except that one or more fields have new
values, use the
<A HREF="../bips/kernel/termmanip/update_struct-4.html"><B>update_struct/4</B></A><A NAME="@default150"></A>
built-in, which allows to do that without having to mention all the
other field names in the structure.<BR>
<BR>
<A NAME="toc24"></A>
<H3 CLASS="subsection"><A NAME="htoc45">5.1.2</A>&nbsp;&nbsp;Arity and Functor of Structures</H3>
The arity of a structure can be symbolically written using <B>of/2</B>
as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
property(arity) of StructName
</PRE></BLOCKQUOTE>
For example,
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- printf("A book has %d fields%n", [property(arity) of book]).
A book has 4 fields
Yes.
</PRE></BLOCKQUOTE>
Similarly, the whole StructName/Arity specification can be written as
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
property(functor) of StructName
</PRE></BLOCKQUOTE>
which is used for the portray-declaration in the example below.<BR>
<BR>
<A NAME="toc25"></A>
<H3 CLASS="subsection"><A NAME="htoc46">5.1.3</A>&nbsp;&nbsp;Printing Structures</H3>
When structures are printed, they are not translated back into the
curly-brace-syntax by default. The reason this is not done is that this can
be bulky if all fields are printed, and often
it is desirable to hide some of the fields anyway.<BR>
<BR>
A good way to control printing of big structures is to write
special purpose portray-transformations for them, for instance
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local portray(property(functor) of book, tr_book_out/2, []).
tr_book_out(book{author:A,title:T},
        no_macro_expansion(book{author:A,title:T})).
</PRE></BLOCKQUOTE>
<A NAME="@default151"></A>
which will cause book/4 structures to be printed like
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
book{author:twain, title:tom sawyer}
</PRE></BLOCKQUOTE>
while the other two arguments remain hidden.<BR>
<BR>
<A NAME="toc26"></A>
<H3 CLASS="subsection"><A NAME="htoc47">5.1.4</A>&nbsp;&nbsp;Inheritance</H3>
<A NAME="@default152"></A>
Structures can be declared to contain other structures,
in which case they inherit the base structure's field names.
Consider the following declarations:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- local struct(person(name,address,age)).
:- local struct(employee(p:person,salary)).
</PRE></BLOCKQUOTE>
The <CODE>employee</CODE> structure contains a field <CODE>p</CODE> which is a
<CODE>person</CODE> structure.
Field names of the <CODE>person</CODE> structure can now be used as if
they were field names of the <CODE>employee</CODE> structure:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]: Emp = employee{name:john,salary:2000}.
Emp = employee(person(john, _105, _106), 2000)
yes.
</PRE></BLOCKQUOTE>
Note that, as long as the <B>curly-brace</B> and <B>of</B> syntax is used,
the <CODE>employee</CODE> structure can be viewed either as nested or as flat,
depending on what is more convenient in a given situation.
In particular, the embedded structure can still be accessed as a whole:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 1]:
        Emp = employee{name:john,age:30,salary:2000,address:here},
        arg(name of employee, Emp, Name),
        arg(age of employee, Emp, Age),
        arg(salary of employee, Emp, Salary),
        arg(address of employee, Emp, Address),
        arg(p of employee, Emp, Person).
        
Emp = employee(person(john, here, 30), 2000)
Name = john
Age = 30
Salary = 2000
Address = here
Person = person(john, here, 30)
yes.
</PRE></BLOCKQUOTE>
The indices of nested structures expand into
lists of integers rather than simple integers,
e.g. <CODE>age of employee</CODE> expands into <CODE>[1,3]</CODE>.<BR>
<BR>
<A NAME="toc27"></A>
<H3 CLASS="subsection"><A NAME="htoc48">5.1.5</A>&nbsp;&nbsp;Visibility</H3>
Structure declaration can be local to a module (when declared as above)
or exported when declared as
<A NAME="@default153"></A>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
:- export struct(...).
</PRE></BLOCKQUOTE>
in the module.<BR>
<BR>
<HR>
<A HREF="umsroot021.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
